﻿using System.Collections.Generic;

namespace lucere.index.read
{
    /// <summary>
    /// TermDocs provides an interface for enumerating &lt;document, frequency&gt;
    /// pairs for a term.  <p> The document portion names each document containing
    /// the term.  Documents are indicated by number.  The frequency portion gives
    /// the number of times the term occurred in each document.  <p> The pairs are
    /// ordered by document number.
    /// </summary>
    public interface ITermDocuments : IEnumerator<IDocumentFrequency>
    {
        void Seek(ITerm term);

        /// <summary>
        /// Sets this to the data for a term.
        /// The enumeration is reset to the start of the data for this term.
        /// </summary>
        /// <param name="termEnum"></param>
        void Seek(ITermEnumerator termEnum);

        /// <summary>
        /// Attempts to read multiple entries from the enumeration, up to length of
        /// <i>docs</i>.  Document numbers are stored in <i>docs</i>, and term
        /// frequencies are stored in <i>freqs</i>.  The <i>freqs</i> array must be as
        /// long as the <i>docs</i> array.
        /// </summary>
        /// <returns>Returns the number of entries read.  Zero is only returned when the 
        /// stream has been exhausted.  </returns>      
        int Read(int[] docs, int[] freqs);

        /// <summary>
        /// Skips entries to the first beyond the current whose document number is
        /// greater than or equal to <i>target</i>. <p>Returns true iff there is such
        /// an entry.  <p>Behaves as if written: <pre>
        /// boolean skipTo(int target) {
        ///     do {
        ///         if (!next())
        ///             return false;
        ///         } while (target > doc());
        ///     return true;
        /// }
        /// </pre>
        /// Some implementations are considerably more efficient than that.
        /// </summary>
        /// <returns>Returns the number of entries read.  Zero is only returned when the 
        /// stream has been exhausted.  </returns>      
        bool SkipTo(int target);
    }
}
